MacHTTP is a server for Macs participating in the World Wide Web (WWW). It allows you to serve hypertext documents to other WWW users from your Macintosh. This version allows you to serve text documents (like HyperText Markup Language documents) as well as binary files (GIFs, f'rinstance). In addition, MacHTTP supports the execution of AppleScripts that can return HTML. This allows you to generate documents on the fly from data base queries, etc. This server works with the standard WWW clients as well as clients like Mosaic that support embedded graphics and it supports HTTP version "0.9".
The server places a very small load on your Mac, both in memory and CPU requirements. It should run fine in the background on any Mac with MacTCP installed and System 7.
MacHTTP is being written by Chuck Shotton, from the University of Texas Houston Health Science Center's Office of Academic Computing. Questions can be addressed to cshotton@oac.hsc.uth.tmc.edu. The latest version of MacHTTP can FTPed from oac.hsc.uth.tmc.edu in the public/mac/MacHTTP directory.
Current information about MacHTTP can be found on the MacHTTP home page at http://www.uth.tmc.edu/mac_info/machttp_info.html.
What's New?
MacHTTP now accepts multiple incoming connections by performing multiple "listens". The number of passive listens for incoming connections is configurable by adjusting the MAXLISTENS value in the config file. Adding this functionality was necessary to support simultaneous attempts by clients to connect to MacHTTP when running high volume servers.
The "close box" has been removed from MacHTTP's status window. Many users were inadvertantly quitting MacHTTP when all they really wanted to do was close the window.
2.0 Installing MacHTTP
System Requirements: MacHTTP requires System 7. If you want to take advantage of advanced features like searchable documents and clickable maps, you also need to have AppleScript installed. Obviously, MacHTTP also needs MacTCP to run.
MacHTTP has been tested on Mac II and Quadra family CPUs and works fine. Unfortunately, MacHTTP doesn't work and play well with 68000-based Macs like SEs and PowerBook 100s. Anyone who figures out why will be rewarded with an immediate upgrade!
Installing MacHTTP is extremely easy. Simply unarchive MacHTTP using a relatively recent version of something like Stuffit Expander or UnStuffit. The resulting folder already has everything installed in the proper places. You may place this folder on any disk, in any location.
Once you have MacHTTP unstuffed, simply double-click the application to activate the server. Use a WWW client like Mac Mosaic to connect to the following URL, substituting your Mac's host name or IP address in place of "your.host.name":
http://your.host.name/
3.0 Configuring MacHTTP
MacHTTP is configured by making changes to the "MacHTTP.config" file found inside the MacHTTP folder. This file consists of a series keywords and arguments that adjust various parameters affecting how MacHTTP runs. MacHTTP.config is a plain text file that can be modified using any text editor, including TeachText.
Configuration File
This section describes the commands that can be entered in the MacHTTP.config file to modify MacHTTP's behavior. Each section describes keywords, their arguments, and provides examples of their use. Open and read the comments in the MacHTTP.config file for more information.
Each command in the config file must start on a line by itself and each line should start with a keyword. Lines that don't start with a recognized keyword are considered as comments. Arguments specified inside angle brackets ("<", ">") should be replaced with the appropriate value for your server in the config file, omitting the angle brackets.
Special Files
There are several commands in the config file that define the names of special files used by MacHTTP.
INDEX <file name>: specifies the Home Page or Index for the server. This is the default document returned if a WWW client accesses your server and specifies the document "/" or no document at all.
If omitted, the default file name is ":Default.html" (no quotes).
ERROR <file name>: specifies the file returned by the server if an error occurs. This is usually an information message informing the user that a requested file cannot be found.
If omitted, the default file name is ":Error.html" (no quotes).
LOG <file name>: specifies the log file for the server. A log of all client accesses is maintained in this file. See the Log File section below for more details.
If omitted, logging is disabled and no log file will be created.
NOACCESS <file name>: specifies the file to be returned by the server if a client that is not authorized to access the server attempts to request a file. See the Security section below for more details.
If omitted, the default file name is ":NoAccess.html" (no quotes).
Examples:
ERROR :Error.html
INDEX :Default.html
LOG :MacHTTP.log
NOACCESS :NoAccess.html
Note that the file names begin with a ":". This tells MacHTTP to look within the same folder as the application for the files. While not required, it's a good idea to make sure the ":" is included for security reasons.
Suffix Mapping
MacHTTP needs to know the difference between text and binary files in order to use the appropriate file transfer method when returning data to a WWW client. For example, HTML (HyperText Markup Language) are text files and need to be converted before transmission to a WWW client because the Macintosh TEXT file format (CR at the ends of lines) is unsuitable for many WWW clients, which expect CR/LF at the ends of lines.
Also, some files like QuickTime movies and GIF images need to be transmitted to the client as byte for byte copies of the original file, using a "binary" transfer mode. In order to help MacHTTP distinguish which transfer method to use, you may specify up to 10 "suffix mappings" in the config file. These mappings tell MacHTTP whether to use a text or binary file transfer when sending a file, based on the suffix of the file's name.
Last of all, MacHTTP can execute AppleScripts and return the results of the script execution back to WWW clients. MacHTTP needs to be able to differentiate between files that are simply sent directly to the client (i.e., binary and text) and files that must be executed first (i.e., AppleScript).
There can be a maximum of 20 suffix mappings defined in the config file. If fewer than 20 mappings are provided, MacHTTP uses internal defaults to supply the missing mappings. When MacHTTP starts up, the status window displays the 20 suffix mappings plus the default file type for file names that don't match one of the 20 mappings.
TEXT <suffix>: Files ending with the specified suffix will have carraige returns translated to carraige return/line feed before transmission to the client.
BINARY <suffix>: Files ending with the specified suffix will be sent to the client without modification. Only the data fork of the file is transmitted.
SCRIPT <suffix>: Files ending with the specified suffix will be loaded and executed as an AppleScript source file. The script is expected to generate HTML text and return it to MacHTTP as the result of script execution. This result will then be transmitted to the client as TEXT files above.
APPL <suffix>: Files ending with the specified suffix will be treated as an application and launched by MacHTTP. MacHTTP will then pass any arguments to the application using custom AppleEvents. The application is expected to generate HTML text and return it to MacHTTP as the result of processing the AppleEvent. This result will then be transmitted to the client as TEXT files above. See the AppleEvents section below for more details.
DEFAULT <type>: "type" can be one of TEXT, BINARY, or SCRIPT. The DEFAULT command specifies the default file type to be used if a file's suffix doesn't match one of the 20 defined suffix mappings.
Examples:
TEXT .HTML
BINARY .GIF
SCRIPT .SCRIPT
APPL .EXE
DEFAULT TEXT
Security
Security can be provided by MacHTTP on a host by host basis. You may specify hosts and networks to ALLOW or DENY access to. MacHTTP matches the IP address of a client requesting a file to a table of security directives. Based on the matches found, MacHTTP will either return the requested file to the client or issue a message (usually from the file specified by the NOACCESS command) saying access is denied.
ALLOW <IP address>: Specifies the partial or complete IP address of a host (or hosts) that is allowed to access the server.
DENY <IP address>: Specifies the partial or complete IP address of a host (or hosts) that is denied access to the server.
An unlimited number of security directives may appear in the config file. If none are present, then any client may access the server. If one or more directives is present in the config file, the directives are evaluated in the order they appear in the config file to determine whether a client is allowed to access the server.
If security directives are present in the config file, there is an implicit "DENY *" that is evaluated before any directives in the file. This means that all clients are denied and you must explicitly allow clients by using the ALLOW command to specify complete or partial addresses of clients which can access the server.
Examples:
ALLOW 129.106.
DENY 129.106.3
ALLOW 129.106.30.1.
These example statements are evaluated as follows. First, the implicit "DENY *" is evaluated, implying that no hosts may access the server. The first ALLOW statement specifies that all clients with addresses that begin with "129.106." will be allowed to connect to the server.
The DENY statement removes all clients with IP addresses that begin with "129.106.3" from the list of hosts that may access the server. Important note: The DENY statement not only matches all hosts in the "129.106.3" subnet, but also all hosts in "129.106.30", "129.106.31", etc. If you wanted to only restrict hosts in the "129.106.3" subnet, you should add a trailing "." to the IP address (i.e., "129.106.3.").
The final ALLOW statement explicitly enables the host "129.106.30.1". This statement matches only this specific host. MacHTTP always appends a trailing "." when comparing a client's IP address to the security entries. This means to match exactly one host with an ALLOW or DENY statement, the IP address argument must end with a "."
Port Number
MacHTTP defaults to listening for all incoming connections on the standard HTTP port 80. It is possible to change this number, allowing multiple MacHTTP servers to run on one Mac on different ports. An example might include running a public access server on port 80 and a restricted access server on port 1080. Note, port numbers below 1024 are reserved for well known services such as telnet, FTP, HTTP, Gopher, etc. If you change the port number for MacHTTP, you should use a number above 1024.
PORT <number>: Specifies the port number that MacHTTP will listen to for all incoming connections. The default is port 80 if this line is omitted from the config file
User Limit
MacHTTP will allow you to define a maximum number of users that may be simultaneously connected to the server. This is useful for servers with limited resources or for extremely busy servers that need to limit the number of queued requests.
The minimum number of simultaneous users is 3. Because of the way MacHTTP handles incoming requests and terminates connections, it is possible for a single, fast client to create a new connection before the previous one is dropped by MacHTTP. This, coupled with the fact that MacHTTP always reserves one connection for listening for incoming client requests means that at least 3 connections should be provided for at a minimum.
The maximum number of users is arbitrarily limited to 1000. Since MacHTTP can only transmit the data for one request to a client at a time, all other clients' requests are queued and executed in turn. Setting the maximum number too high will result in intolerable delays for clients. These delays could exceed MacHTTP's timeout value for inactive connections, so it's probably a good idea to leave the maximum users setting somewhere between 8 and 20.
Incoming clients that exceed the maximum number of users will be informed that the server is too busy to handle their request.
MAXUSERS <number>: Specify the maximum number of simultaneous users allowed to connect to MacHTTP. Values between 3 and 1000 are allowed. The default is 8 if this statement is omitted from the config file.
Listening for Clients
Older versions of MacHTTP would listen for a single incoming connection. On busy servers, this often caused clients to receive "Unable to connect" errors because MacHTTP was unable to process an incoming connection and get ready for a new one quickly enough. MacHTTP now supports a configurable number of "listens", allowing the server to handle multiple, simultaneous, incoming connections.
MAXLISTENS <number>: Defines the number of simultaneous listens for incoming client connections. Values between 3 and 50 are allowed. The default is 5.
Timeout
MacHTTP will disconnect any client that fails to interact with the server after a specified amount of idle time has passed. If it takes longer than the timeout period for MacHTTP to complete a client's request (i.e., the server is busy, or an AppleScript takes a long time to execute), the client will be disconnected as well. Therefore, it is important to monitor the average time that clients wait in the queue and adjust this value accordingly.
TIMEOUT <seconds>: Specifies the maximum amount of idle time in seconds before MacHTTP disconnects a client's inactive connection. The minimum value is 15 seconds. The maximum value is 600 seconds and the default is 90 seconds if this statement is omitted from the config file.
Hiding in the Background
MacHTTP can optionally hide its status window when running in the background. This feature can be temporarily set from the Option menu or set permanently by using the HIDEWINDOW command in the config file.
HIDEWINDOW: If this command is present in the config file, MacHTTP's status window will be hidden when the application is running in the background.
MacHTTP Menus
Most configuration of MacHTTP occurs in the config file. However, certain options that affect the status window server behavior are implemented as menus. This section describes the functions contained in these menus.
All MacHTTP menu functions can be invoked via AppleEvents. So if MacHTTP is running on a "headless" Mac or you want to use AppleScript to control its behavior, you may execute any of the menu commands from another application. See the "Scripting and MacHTTP" section below or examine MacHTTP's AppleEvent dictionary (aete reource) for more details.
File Menu
This one is simple. All you can do is quit.
Edit Menu
This, too, is an easy to explain menu. It does nothing and is included because Apple's Human Interface guidelines suggest that an Edit menu be included in all applications.
Options Menu
This menu actually does something interesting. This menu contains commands that enable or disable certain MacHTTP functions.
Verbose Messages: Causes MacHTTP to produce much more status information about client requests and what the program is doing internally. You should enable this option if you are having trouble with MacHTTP and aren't sure what's going on. The cryptic nature of these messages is sure to help add to the confusion, since most pertain to internal MacTCP state information. However, some of the messages are useful for watching details of client requests, etc.
Suspend Logging: Temporarily closes MacHTTP's log file (if a log file is specified in the config file), allowing you to open and examine the log file with a text editor. All incoming connection information will not be logged to the file while this option is enabled.
Hide Window in Background: Works the same as the HIDEWINDOW command in the config file, described above.
Refuse New Connections: This option allows busy servers to remain running, but not allow any new clients to connect. All currently queued clients will be served, but no new connections will be accepted. Clients will be notified that connections are being refused. This option is useful for gracefully shutting down a server, or allowing you to change HTML documents while the server is running.
4.0 Serving Documents
HTML documents, including file references, links, anchors, and naming conventions used by MacHTTP are 100% compatible with those used by Unix-based HTTP servers. MacHTTP communicates with WWW clients running on any platform.
It is important to note that MacHTTP can interpret both Unix and Mac file specifications. Typically, HTML documents are written using Unix path names, etc. while file names specified within MacHTTP's config file use Mac file naming conventions.
MacHTTP also understands Macintosh aliases. If you create an alias to a document for MacHTTP to serve, MacHTTP will use the name of the alias for suffix mapping, then translate the alias to find the original file's contents.
File Locations
MacHTTP always expects that the files requested by WWW clients will reside in the same folder as MacHTTP, or subfolders within this folder. This means that clients cannot explicitly request files that live outside of the folder tree where MacHTTP resides. MacHTTP behaves this way for security reasons, since this prevents people for requesting files on your Mac besides those you explicitly place within the view of MacHTTP.
This means that the "root" of MacHTTP's file system starts with the folder it resides in. Clients requesting documents from MacHTTP specify URLs as if MacHTTP was at the root of the file system.
How MacHTTP interprets file names
MacHTTP goes through the following steps when interpreting a client's request for a specific file:
• Translation of special characters - MacHTTP converts all HTTP special characters (i.e. %xx, where "xx" is the two-digit hex number of the special character.)
• Pathname conversion - MacHTTP converts all slashes ("/") in Unix style pathnames to colons (":") as used by the Mac file system.
• Double-colon removal - MacHTTP removes all occurences of "::" and replaces them with a single colon (":"). This prevents clients from specifying parent directories in the Mac file system.
• Suffix interpretation - The suffix of the requested file is extracted and used to determine the actions MacHTTP will perform on the file.
• Alias Translation - MacHTTP determines if the requested file name (as modified by the preceding steps) is an alias and if so, translates it to the real path for the file.
• File transmission - The file represented by the file name is opened. If the suffix of the file indicated that it is a binary file, its contents are returned immediately with no modification. If the file is a text file (e.g., HTML), it is read in and all carraige returns are converted to carraige return/line feed before transmission. If the file is a script, MacHTTP generates the appropriate AppleScript arguments (see below), concatenates them to the AppleScript source code contained in the file, executes the script, and translates and returns the result to the client as text.
NOTE: While you can use aliases to original files that aren't contained within the MacHTTP directory tree, any URLs contained in these files must still provide paths that are relative to where MacHTTP resides. This is done for security purposes and isn't subject to change.
URL Examples
Assume the following. Suppose MacHTTP is installed on a drive called "Hard Disk", inside a folder called "WWW". In the "WWW" folder are the files from the MacHTTP distribution, a text document called sample.html, and a subfolder called More_Docs. Inside More_Docs is a text file called another.html.
To access your default home page, you'd specify the following URL:
http://your.host.name/
To access "sample.html" :
http://your.host.name/sample.html
To access "another.html" :
http://your.host.name/More_Docs/another.html
Note that all URLs are relative to the folder containing MacHTTP. No parent directories or disks are specified. MacHTTP handles spaces and special characters in folder and file names, but it's a good idea to avoid spaces and special characters in any file or folder names that MacHTTP will be serving when possible.
MacHTTP tries to deal intelligently with HTTP 1.0 clients (by discarding everything after the path.) It supports query URLs and special character translation in URLs, but not returning data over alternate ports. It also supports returning binary data, so it can be used with clients that support graphics (like Mosaic).
More information on URLs can be obtained from http://www.ncsa.uiuc.edu/demoweb/url-primer.html.
Information on writing HTML documents for WWW can be obtained from http://www.ncsa.uiuc.edu/demoweb/html-primer.html.
Serving Documents from Mac Applications
In addition to serving documents like HTML and GIF files, MacHTTP can serve documents from many other types of Mac applications with a few caveats:
• Documents must contain all of their data in the data fork of the Mac file.
• Suffix mappings must be defined for the documents that cause them to be sent as binary files (more below).
• The documents will not be viewable by users on other machines that don't possess applications capable of reading the Mac files.
Configuring MacHTTP to Serve Mac Documents
There is only one real configuration issue on the MacHTTP side of things to contend with. You must make sure your Mac documents (e.g, Word, Excel) are named with a suffix that is defined in the MacHTTP.config file as BINARY. You are limited to only 20 suffix definitions, so you may need to redefine some that you aren't using.
Here's an example. Suppose you have an Excel spreadsheet file called "BigBucks.xcl". You must make sure that there is an entry in the MacHTTP.config file that looks like:
BINARY .xcl
This tells MacHTTP to transfer files with names ending in ".xcl" to the WWW client without any modifications.
Configuring your WWW client is the next step. If you are using Mac Mosaic, you need to define a file name extension mapping that maps the ".xcl" suffix into a specific MIME type and "Helper Application." Once you've done this, selecting a URL like http://your.machttp.host/BigBucks.xcl
Scripting, AppleEvents, and MacHTTP
If you have AppleScript installed on your Mac, MacHTTP can execute AppleScripts and return the results as a document to clients. To do this, place a text-only version of a script in a location where MacHTTP can find it. Make sure that the MacHTTP.config file contains an entry for SCRIPT files and that your script is named with the appropriate suffix.
Any WWW client accessing a SCRIPT document will cause MacHTTP to load the source for the script from the file specified in the URL. Two predefined AppleScript variables are created and prepended to the AppleScript source. MacHTTP will then pass the source code to AppleScript for compilation and execution. The result returned from AppleScript is then passed back to the client by MacHTTP.
MacHTTP AppleScript Variables
MacHTTP assigns values to two global variables which are available to all AppleScripts when they execute.
http_request contains the complete HTTP request received from the WWW client. http_search_args contains any search arguments passed by the WWW client to MacHTTP as part of the request. This variable is useful for implementing clickable maps and searchable documents. See the example script files in the MacHTTP distribution for more details on how these variables are used.
Searchable Documents
You can use the ability to execute scripts to implement searchable documents. The following is an example of an AppleScript that presents a menu to the user and receives search keywords from a WWW client:
if http_search_args = "" then
return "<ISINDEX><h2>Please enter the keyword to search for.</h2>"
else if http_search_args = "hello" then
return "<h2>Hello, how are you?</h2>"
else
return "<h2>Sorry, I don't understand '" & http_search_args &
"'. Try 'hello' instead.</h2>"
end if
http_search_args is a variable that is predefined by MacHTTP, prior to script execution, that contains the search arguments passed by the WWW client. < ISINDEX> is a HTML tag that indicates the following document is searchable. Be careful not to confuse "ISINDEX" with the INDEX file specification described above.
Some important notes:
1. AppleScript source files MUST be TEXT files (Save as... Text only)
2. MacHTTP prefixes every source file with global variable definitions prior to passing it to AppleScript. A variable called "http_request" contains a string that is the actual argument passed to MacHTTP by the WWW client. This may be useful if you have a client that sends HTML1 requests and you want to do something with the extra arguments in AppleScript.
Another variable, "http_search_args", contains the search arguments, if any, that were passed as part of the client's request. This info is also contained in the http_request variable, but is extracted and provided for easier access here.
See the sample.script and search.script files for examples.
3. You must perform all HTML formatting inside the AppleScript file. MacHTTP only strips off the spurious quotes and converts special characters prior to sending script execution results to the client. Again, see the sample.script file for examples.
4. If MacHTTP is low on memory, scripts that use scripting extensions (OSAX's) will cause the program to hang. Make sure MacHTTP has enough memory (512K for script execution, 384K otherwise).
5. You may place alias files in your MacHTTP directory tree that point to script files. If the alias name ends with a suffix that is defined to be of type "SCRIPT", then the alias will be resolved and the file will be executed.
MacHTTP and AppleEvents
MacHTTP supports the 4 required AppleEvents, plus a custom AppleEvent suite for communicating with MacHTTP while it is running. The 4 required events don't do much, since MacHTTP doesn't open or print any documents of its own. However, the custom event suite is very useful for operating MacHTTP under script control or from a remote Mac.
AppleEvents Received by MacHTTP
Currently, there is only one custom AppleEvent supported by MacHTTP. This event, DoMenu,is used to make MacHTTP execute one of its menu choices. The syntax from AppleScript is:
DoMenu "<menu ID>, < menu item>"
"Menu ID" is the number of the MacHTTP menu, starting with 1 for the Apple menu and ending with 4 for the Options menu. "Menu Item" is the selection within a particular menu. For example:
DoMenu "4,1"
would turn on Verbose Messages (menu 4, Options, item 1, Verbose Messages).
The event suite for the DoMenu event is the same as the 4 character creator code for MacHTTP. This is three upper case "W"s, followed by the omega character (generated by typing option-Z). The event code for DoMenu is the 4 character code, "menu". See the MacHTTP aete resource for more details (MacHTTP's "dictionary" for AppleScript users).
AppleEvents Sent by MacHTTP
If MacHTTP receives a query (GET) from a WWW client requesting a file whose suffix mapping is APPL (an executable application), MacHTTP will attempt to execute this application and communicate with it via custom AppleEvents. Currently, MacHTTP supports one AppleEvent for communication with traditional Mac applications or AppleScript applications.
Search: The "search" AppleEvent that is part of the MacHTTP suite is sent to applications when they are specified in a URL being requested by a WWW client. MacHTTP will launch the application, and then send this event. Here are the specifics on the search event:
• The four character Event Suite is 'WWW*', where "*" is actually the omega character generated by typing option-Z (HTML cannot represent this character in this document correctly).
• The four character event code is 'srch'
• The direct parameter contains the search arguments as passed from the WWW client to MacHTTP.
• MacHTTP expects the AppleEvent reply's direct parameter to contain HTML text that will be transmitted to the client.
If you are a C or Pascal programmer, the above information will make sense. If you are creating compiled AppleScript applications, see the "search.exe" file contained in the AppleScript folder which is part of the MacHTTP distribution for an example of how to handle receiving events from MacHTTP. Briefly, AppleScript applications that contain a handler that starts with the line:
on <<event WWW*srch>> search_args --remember, "*" is the omega char!
will be launched automatically, and the handler will be invoked with search_args appropriately defined. Note that "<<" and ">>" are the single characters obtained by typing option-\ and option-|, respectively.
5.0 Administering MacHTTP
Security Considerations
Every effort has been made to ensure that no access to files outside the MacHTTP folder can take place. MacHTTP only provides READ-ONLY access to files in its directory tree. HOWEVER, if you allow AppleScript execution, the burden falls on the script writer to make sure nothing naughty can happen.
If you don't want to allow script execution (or don't have AppleScript installed) you can make sure script execution is disabled by modifying the MacHTTP.config file so none of the 10 entries defines a SCRIPT type.
As configured "out of the box", MacHTTP provides no restrictions on which hosts may access your server. Please review the section above that describes the ALLOW and DENY commands in the configuration file, which are used to restrict network access to MacHTTP.
Log File
MacHTTP defaults to logging all transactions to a file in the same directory as the MacHTTP application. The standard name for this file is MacHTTP.log, but you may change this by modifying the configuration file entry (LOG).
Entries in the log file are separated by tabs, and individual entries are terminated with a carraige return. This format is the standard text-only import format used by most spreadsheet applications (e.g. Excel) and Mac data base applications like FileMaker.
To disable logging, simply delete the log file specification command from the config file (LOG :MacHTTP.log).
